<!DOCTYPE html>
            <html>
                <head>                    
                    <meta http-equiv="X-UA-Compatible" content="IE=edge">
                    <meta http-equiv="content-type" content="text/html; charset=utf-8">
                    <title>Units C API Document.md</title>
                    <style type="text/css">
                    /*
Copyright (c) 2017 Chris Patuzzo
https://twitter.com/chrispatuzzo
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

body {
  font-family: Helvetica, arial, sans-serif;
  font-size: 14px;
  line-height: 1.6;
  padding-top: 10px;
  padding-bottom: 10px;
  background-color: white;
  padding: 30px;
  color: #333;
}

body &gt; *:first-child {
  margin-top: 0 !important;
}

body &gt; *:last-child {
  margin-bottom: 0 !important;
}

a {
  color: #4183C4;
  text-decoration: none;
}

a.absent {
  color: #cc0000;
}

a.anchor {
  display: block;
  padding-left: 30px;
  margin-left: -30px;
  cursor: pointer;
  position: absolute;
  top: 0;
  left: 0;
  bottom: 0;
}

h1, h2, h3, h4, h5, h6 {
  margin: 20px 0 10px;
  padding: 0;
  font-weight: bold;
  -webkit-font-smoothing: antialiased;
  cursor: text;
  position: relative;
}

h2:first-child, h1:first-child, h1:first-child + h2, h3:first-child, h4:first-child, h5:first-child, h6:first-child {
  margin-top: 0;
  padding-top: 0;
}

h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, h5:hover a.anchor, h6:hover a.anchor {
  text-decoration: none;
}

h1 tt, h1 code {
  font-size: inherit;
}

h2 tt, h2 code {
  font-size: inherit;
}

h3 tt, h3 code {
  font-size: inherit;
}

h4 tt, h4 code {
  font-size: inherit;
}

h5 tt, h5 code {
  font-size: inherit;
}

h6 tt, h6 code {
  font-size: inherit;
}

h1 {
  font-size: 28px;
  color: black;
}

h2 {
  font-size: 24px;
  border-bottom: 1px solid #cccccc;
  color: black;
}

h3 {
  font-size: 18px;
}

h4 {
  font-size: 16px;
}

h5 {
  font-size: 14px;
}

h6 {
  color: #777777;
  font-size: 14px;
}

p, blockquote, ul, ol, dl, li, table, pre {
  margin: 15px 0;
}

/*
hr {
  border: 0 none;
  color: #cccccc;
  height: 4px;
  padding: 0;
}
*/
body &gt; h2:first-child {
  margin-top: 0;
  padding-top: 0;
}

body &gt; h1:first-child {
  margin-top: 0;
  padding-top: 0;
}

body &gt; h1:first-child + h2 {
  margin-top: 0;
  padding-top: 0;
}

body &gt; h3:first-child, body &gt; h4:first-child, body &gt; h5:first-child, body &gt; h6:first-child {
  margin-top: 0;
  padding-top: 0;
}

a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
  margin-top: 0;
  padding-top: 0;
}

h1 p, h2 p, h3 p, h4 p, h5 p, h6 p {
  margin-top: 0;
}

li p.first {
  display: inline-block;
}

ul, ol {
  padding-left: 30px;
}

ul :first-child, ol :first-child {
  margin-top: 0;
}

ul :last-child, ol :last-child {
  margin-bottom: 0;
}

dl {
  padding: 0;
}

dl dt {
  font-size: 14px;
  font-weight: bold;
  font-style: italic;
  padding: 0;
  margin: 15px 0 5px;
}

dl dt:first-child {
  padding: 0;
}

dl dt &gt; :first-child {
  margin-top: 0;
}

dl dt &gt; :last-child {
  margin-bottom: 0;
}

dl dd {
  margin: 0 0 15px;
  padding: 0 15px;
}

dl dd &gt; :first-child {
  margin-top: 0;
}

dl dd &gt; :last-child {
  margin-bottom: 0;
}

blockquote {
  border-left: 4px solid #dddddd;
  padding: 0 15px;
  color: #777777;
}

blockquote &gt; :first-child {
  margin-top: 0;
}

blockquote &gt; :last-child {
  margin-bottom: 0;
}

table {
  padding: 0;
}
table tr {
  border-top: 1px solid #cccccc;
  background-color: white;
  margin: 0;
  padding: 0;
}

table tr:nth-child(2n) {
  background-color: #f8f8f8;
}

table tr th {
  font-weight: bold;
  border: 1px solid #cccccc;
  text-align: left;
  margin: 0;
  padding: 6px 13px;
}

table tr td {
  border: 1px solid #cccccc;
  text-align: left;
  margin: 0;
  padding: 6px 13px;
}

table tr th :first-child, table tr td :first-child {
  margin-top: 0;
}

table tr th :last-child, table tr td :last-child {
  margin-bottom: 0;
}

img {
  max-width: 100%;
}

span.frame {
  display: block;
  overflow: hidden;
}

span.frame &gt; span {
  border: 1px solid #dddddd;
  display: block;
  float: left;
  overflow: hidden;
  margin: 13px 0 0;
  padding: 7px;
  width: auto;
}

span.frame span img {
  display: block;
  float: left;
}

span.frame span span {
  clear: both;
  color: #333333;
  display: block;
  padding: 5px 0 0;
}

span.align-center {
  display: block;
  overflow: hidden;
  clear: both;
}

span.align-center &gt; span {
  display: block;
  overflow: hidden;
  margin: 13px auto 0;
  text-align: center;
}

span.align-center span img {
  margin: 0 auto;
  text-align: center;
}

span.align-right {
  display: block;
  overflow: hidden;
  clear: both;
}

span.align-right &gt; span {
  display: block;
  overflow: hidden;
  margin: 13px 0 0;
  text-align: right;
}

span.align-right span img {
  margin: 0;
  text-align: right;
}

span.float-left {
  display: block;
  margin-right: 13px;
  overflow: hidden;
  float: left;
}

span.float-left span {
  margin: 13px 0 0;
}

span.float-right {
  display: block;
  margin-left: 13px;
  overflow: hidden;
  float: right;
}

span.float-right &gt; span {
  display: block;
  overflow: hidden;
  margin: 13px auto 0;
  text-align: right;
}

code, tt {
  margin: 0 2px;
  padding: 0 5px;
  white-space: nowrap;
  border: 1px solid #eaeaea;
  background-color: #f8f8f8;
  border-radius: 3px;
}

pre code {
  margin: 0;
  padding: 0;
  white-space: pre;
  border: none;
  background: transparent;
}

.highlight pre {
  background-color: #f8f8f8;
  border: 1px solid #cccccc;
  font-size: 13px;
  line-height: 19px;
  overflow: auto;
  padding: 6px 10px;
  border-radius: 3px;
}

pre {
  background-color: #f8f8f8;
  border: 1px solid #cccccc;
  font-size: 13px;
  line-height: 19px;
  overflow: auto;
  padding: 6px 10px;
  border-radius: 3px;
}

pre code, pre tt {
  background-color: transparent;
  border: none;
}

/* Syntax Highlighting */

.plainText {
 background-color: #FFFFFF;
 color: #000000;
}
.htmlServerSideScript {
 background-color: #FFFF00;
}
.htmlComment {
 color: #008000;
}
.htmlTagDelimiter {
 color: #0000FF;
}
.htmlElementName {
 color: #A31515;
}
.htmlAttributeName {
 color: #FF0000;
}
.htmlAttributeValue {
 color: #0000FF;
}
.htmlOperator {
 color: #0000FF;
}
.comment {
 color: #008000;
}
.xmlDocTag {
 color: #808080;
}
.xmlDocComment {
 color: #008000;
}
.string {
 color: #A31515;
}
.stringCSharpVerbatim {
 color: #A31515;
}
.keyword {
 color: #0000FF;
}
.preprocessorKeyword {
 color: #0000FF;
}
.htmlEntity {
 color: #FF0000;
}
.xmlAttribute {
 color: #FF0000;
}
.xmlAttributeQuotes {
 color: #000000;
}
.xmlAttributeValue {
 color: #0000FF;
}
.xmlCDataSection {
 color: #808080;
}
.xmlComment {
 color: #008000;
}
.xmlDelimiter {
 color: #0000FF;
}
.xmlName {
 color: #A31515;
}
.className {
 color: #48D1CC;
}
.cssSelector {
 color: #A31515;
}
.cssPropertyName {
 color: #FF0000;
}
.cssPropertyValue {
 color: #0000FF;
}
.sqlSystemFunction {
 color: #FF00FF;
}
.powershellAttribute {
 color: #B0E0E6;
}
.powershellOperator {
 color: #808080;
}
.powershellType {
 color: #008080;
}
.powershellVariable {
 color: #FF4500;
}
.type {
 color: #008080;
}
.typeVariable {
 color: #008080;
 font-style: italic;
}
.namespace {
 color: #000080;
}
.constructor {
 color: #800080;
}
.predefined {
 color: #000080;
}
.pseudoKeyword {
 color: #000080;
}
.stringEscape {
 color: #808080;
}
.controlKeyword {
 color: #0000FF;
}
.number {
}
.operator {
}
.delimiter {
}
.markdownHeader {
 font-weight: bold;
}
.markdownCode {
 color: #008080;
}
.markdownListItem {
 font-weight: bold;
}
.italic {
 font-style: italic;
}
.bold {
 font-weight: bold;
}

                    </style>
                </head>
                <body style="">
                <h1 id="0">Units C API 文档</h1>
<h2 id="2">概述</h2>
<p id="4">Units C API 是一个用于单位转换和管理的 C 语言接口库。该库提供了丰富的功能，包括单位转换、自定义单位注册、配置文件管理等。</p>
<h2 id="6">基本使用流程</h2>
<ol id="8">
<li id="8">调用 <code>units_create</code> 创建单位系统实例</li>
<li id="9">使用各种 API 进行单位转换和管理操作</li>
<li id="10">调用 <code>units_destroy</code> 销毁实例释放资源</li>
</ol>
<h2 id="12">数据类型</h2>
<h3 id="14">UnitsHandle</h3>
<p id="15">单位系统句柄，用于标识一个单位系统实例。</p>
<h3 id="17">UnitsErrorCode</h3>
<p id="18">错误码枚举类型，表示函数执行结果：</p>
<table id="20">
<thead>
<tr id="20">
<th id="20">错误码</th>
<th id="20">值</th>
<th id="20">说明</th>
</tr>
</thead>
<tbody>
<tr id="22">
<td id="22">UNITS_SUCCESS</td>
<td id="22">0</td>
<td id="22">操作成功</td>
</tr>
<tr id="23">
<td id="23">UNITS_INVALID_HANDLE</td>
<td id="23">1</td>
<td id="23">无效的句柄</td>
</tr>
<tr id="24">
<td id="24">UNITS_INVALID_PARAM</td>
<td id="24">2</td>
<td id="24">无效参数</td>
</tr>
<tr id="25">
<td id="25">UNITS_DIMENSION_NOT_FOUND</td>
<td id="25">3</td>
<td id="25">未找到维度</td>
</tr>
<tr id="26">
<td id="26">UNITS_UNIT_NOT_FOUND</td>
<td id="26">4</td>
<td id="26">未找到单位</td>
</tr>
<tr id="27">
<td id="27">UNITS_CONVERSION_FAILED</td>
<td id="27">5</td>
<td id="27">转换失败</td>
</tr>
<tr id="28">
<td id="28">UNITS_CUSTOM_CONV_EXISTS</td>
<td id="28">6</td>
<td id="28">自定义转换已存在</td>
</tr>
<tr id="29">
<td id="29">UNITS_FILE_IO_ERROR</td>
<td id="29">7</td>
<td id="29">文件IO错误</td>
</tr>
<tr id="30">
<td id="30">UNITS_CONFIG_PARSE_ERROR</td>
<td id="30">8</td>
<td id="30">配置解析错误</td>
</tr>
<tr id="31">
<td id="31">UNITS_INVALID_UNIT</td>
<td id="31">9</td>
<td id="31">无效单位</td>
</tr>
<tr id="32">
<td id="32">UNITS_DEFINED_UNITS_PARSE_ERROR</td>
<td id="32">10</td>
<td id="32">已定义单位解析错误</td>
</tr>
<tr id="33">
<td id="33">UNITS_UNKNOWN_ERROR</td>
<td id="33">11</td>
<td id="33">未知错误</td>
</tr>
</tbody>
</table>
<h2 id="35">核心API</h2>
<h3 id="37">units_create</h3>
<p id="38">创建一个新的单位系统实例</p>
<div id="40" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_create(UnitsHandle *handle);
</pre></div>
</div>
<p id="44"><strong>参数</strong>:</p>
<ul id="45">
<li id="45"><code>handle</code>: 指向新创建的单位系统句柄的指针</li>
</ul>
<p id="47"><strong>返回值</strong>:</p>
<ul id="48">
<li id="48"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="49"><code>UNITS_INVALID_PARAM</code>: handle 为空指针</li>
<li id="50"><code>UNITS_UNKNOWN_ERROR</code>: 内存分配失败或其他未知错误</li>
</ul>
<h3 id="52">units_destroy</h3>
<p id="53">销毁一个已有的单位系统实例</p>
<div id="55" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_destroy(UnitsHandle handle);
</pre></div>
</div>
<p id="59"><strong>参数</strong>:</p>
<ul id="60">
<li id="60"><code>handle</code>: 要销毁的单位系统句柄</li>
</ul>
<p id="62"><strong>返回值</strong>:</p>
<ul id="63">
<li id="63"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="64"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
</ul>
<h2 id="66">单位转换API</h2>
<h3 id="68">units_convert_measurement</h3>
<p id="69">将字符串形式的测量值转换为目标单位</p>
<div id="71" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_convert_measurement(UnitsHandle handle,
                                         <span class="keyword">const</span> <span class="keyword">char</span> *measurement,
                                         <span class="keyword">const</span> <span class="keyword">char</span> *to,
                                         <span class="keyword">double</span> *result);
</pre></div>
</div>
<p id="78"><strong>参数</strong>:</p>
<ul id="79">
<li id="79"><code>handle</code>: 单位系统句柄</li>
<li id="80"><code>measurement</code>: 输入的测量值字符串（如 &quot;10 meters&quot;）</li>
<li id="81"><code>to</code>: 目标单位名称</li>
<li id="82"><code>result</code>: 转换后的数值结果（输出参数）</li>
</ul>
<p id="84"><strong>返回值</strong>:</p>
<ul id="85">
<li id="85"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="86"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="87"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="88">其他转换相关错误码</li>
</ul>
<p id="90"><strong>示例</strong>:</p>
<div id="92" class="lang-c editor-colors"><div class="cplusplus"><pre>
<span class="keyword">double</span> result;
UnitsHandle handle;
units_create(&amp;handle);
units_convert_measurement(handle, <span class="string">&quot;10 meters&quot;</span>, <span class="string">&quot;feet&quot;</span>, &amp;result);
<span class="comment">// result 约等于 32.8084</span>
units_destroy(handle);
</pre></div>
</div>
<h3 id="101">units_convert</h3>
<p id="102">数值单位转换接口</p>
<div id="104" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_convert(UnitsHandle handle, <span class="keyword">double</span> <span class="keyword">value</span>,
                             <span class="keyword">const</span> <span class="keyword">char</span> *from, <span class="keyword">const</span> <span class="keyword">char</span> *to,
                             <span class="keyword">double</span> *result);
</pre></div>
</div>
<p id="110"><strong>参数</strong>:</p>
<ul id="111">
<li id="111"><code>handle</code>: 单位系统句柄</li>
<li id="112"><code>value</code>: 待转换的数值</li>
<li id="113"><code>from</code>: 源单位名称</li>
<li id="114"><code>to</code>: 目标单位名称</li>
<li id="115"><code>result</code>: 转换后的数值结果（输出参数）</li>
</ul>
<p id="117"><strong>返回值</strong>:</p>
<ul id="118">
<li id="118"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="119"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="120"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="121"><code>UNITS_UNIT_NOT_FOUND</code>: 未找到单位</li>
<li id="122"><code>UNITS_CONVERSION_FAILED</code>: 转换失败</li>
</ul>
<p id="124"><strong>示例</strong>:</p>
<div id="126" class="lang-c editor-colors"><div class="cplusplus"><pre>
<span class="keyword">double</span> result;
UnitsHandle handle;
units_create(&amp;handle);
units_convert(handle, 100.0, <span class="string">&quot;meter&quot;</span>, <span class="string">&quot;kilometer&quot;</span>, &amp;result);
<span class="comment">// result = 0.1</span>
units_destroy(handle);
</pre></div>
</div>
<h3 id="135">units_convert_to_base</h3>
<p id="136">将数值从指定维度转换为基本单位</p>
<div id="138" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_convert_to_base(UnitsHandle handle, <span class="keyword">double</span> <span class="keyword">value</span>,
                                     <span class="keyword">const</span> <span class="keyword">char</span> *dimension,
                                     <span class="keyword">double</span> *result);
</pre></div>
</div>
<p id="144"><strong>参数</strong>:</p>
<ul id="145">
<li id="145"><code>handle</code>: 单位系统句柄</li>
<li id="146"><code>value</code>: 待转换的数值</li>
<li id="147"><code>dimension</code>: 维度名称（如 &quot;length&quot;, &quot;mass&quot; 等）</li>
<li id="148"><code>result</code>: 转换后的数值结果（输出参数）</li>
</ul>
<p id="150"><strong>返回值</strong>:</p>
<ul id="151">
<li id="151"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="152"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="153"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="154"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
</ul>
<h3 id="156">units_convert_from_base</h3>
<p id="157">将数值从基本单位转换为指定维度的单位</p>
<div id="159" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_convert_from_base(UnitsHandle handle,
                                       <span class="keyword">double</span> <span class="keyword">value</span>,
                                       <span class="keyword">const</span> <span class="keyword">char</span> *dimension,
                                       <span class="keyword">double</span> *result);
</pre></div>
</div>
<p id="166"><strong>参数</strong>:</p>
<ul id="167">
<li id="167"><code>handle</code>: 单位系统句柄</li>
<li id="168"><code>value</code>: 待转换的数值</li>
<li id="169"><code>dimension</code>: 维度名称</li>
<li id="170"><code>result</code>: 转换后的数值结果（输出参数）</li>
</ul>
<p id="172"><strong>返回值</strong>:- <code>UNITS_SUCCESS</code>: 成功</p>
<ul id="173">
<li id="173"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="174"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="175"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
</ul>
<h2 id="177">单位管理API</h2>
<h3 id="179">units_set_base_unit</h3>
<p id="180">设置某个维度的基本单位</p>
<p id="182"><strong>参数</strong>:</p>
<ul id="183">
<li id="183"><code>handle</code>: 单位系统句柄</li>
<li id="184"><code>dimension</code>: 维度名称</li>
<li id="185"><code>unit</code>: 单位名称</li>
</ul>
<p id="187"><strong>返回值</strong>:</p>
<ul id="188">
<li id="188"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="189"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="190"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="191"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
<li id="192"><code>UNITS_CONVERSION_FAILED</code>: 转换失败</li>
</ul>
<h3 id="194">units_set_current_unit</h3>
<p id="195">设置某个维度的当前使用单位</p>
<div id="197" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_set_base_unit(UnitsHandle handle,
                                   <span class="keyword">const</span> <span class="keyword">char</span> *dimension,
                                   <span class="keyword">const</span> <span class="keyword">char</span> *unit);
</pre></div>
</div>
<p id="203"><strong>参数</strong>:</p>
<ul id="204">
<li id="204"><code>handle</code>: 单位系统句柄</li>
<li id="205"><code>dimension</code>: 维度名称</li>
<li id="206"><code>unit</code>: 单位名称</li>
</ul>
<p id="208"><strong>返回值</strong>:</p>
<ul id="209">
<li id="209"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="210"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="211"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="212"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
<li id="213"><code>UNITS_CONVERSION_FAILED</code>: 转换失败</li>
</ul>
<h3 id="215">units_get_base_unit</h3>
<p id="216">获取某个维度的基本单位名称</p>
<div id="218" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_get_base_unit(UnitsHandle handle,
                                   <span class="keyword">const</span> <span class="keyword">char</span> *dimension,
                                   <span class="keyword">char</span> *buffer,
                                   <span class="keyword">unsigned</span> <span class="keyword">int</span> buf_size);
</pre></div>
</div>
<p id="225"><strong>参数</strong>:</p>
<ul id="226">
<li id="226"><code>handle</code>: 单位系统句柄</li>
<li id="227"><code>dimension</code>: 维度名称</li>
<li id="228"><code>buffer</code>: 存储结果的缓冲区</li>
<li id="229"><code>buf_size</code>: 缓冲区大小</li>
</ul>
<p id="231"><strong>返回值</strong>:</p>
<ul id="232">
<li id="232"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="233"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="234"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="235"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
</ul>
<h3 id="237">units_get_current_unit</h3>
<p id="238">获取某个维度的当前使用单位名称</p>
<div id="240" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_get_current_unit(UnitsHandle handle,
                                      <span class="keyword">const</span> <span class="keyword">char</span> *dimension,
                                      <span class="keyword">char</span> *buffer,
                                      <span class="keyword">unsigned</span> <span class="keyword">int</span> buf_size);
</pre></div>
</div>
<p id="247"><strong>参数</strong>:</p>
<ul id="248">
<li id="248"><code>handle</code>: 单位系统句柄</li>
<li id="249"><code>dimension</code>: 维度名称</li>
<li id="250"><code>buffer</code>: 存储结果的缓冲区</li>
<li id="251"><code>buf_size</code>: 缓冲区大小</li>
</ul>
<p id="253"><strong>返回值</strong>:</p>
<ul id="254">
<li id="254"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="255"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="256"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="257"><code>UNITS_DIMENSION_NOT_FOUND</code>: 未找到维度</li>
</ul>
<h2 id="259">自定义单位API</h2>
<h3 id="261">units_register_defined_unit</h3>
<p id="262">注册一个自定义单位定义</p>
<div id="264" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_register_defined_unit(UnitsHandle handle,
                                           <span class="keyword">const</span> <span class="keyword">char</span> *name,
                                           <span class="keyword">const</span> <span class="keyword">char</span> *definition);
</pre></div>
</div>
<p id="270"><strong>参数</strong>:</p>
<ul id="271">
<li id="271"><code>handle</code>: 单位系统句柄</li>
<li id="272"><code>name</code>: 单位名称</li>
<li id="273"><code>definition</code>: 单位定义表达式</li>
</ul>
<p id="275"><strong>返回值</strong>:</p>
<ul id="276">
<li id="276"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="277"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="278"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="279">UNITS_CUSTOM_CONV_EXISTS: 自定义转换已存在</li>
</ul>
<p id="281"><strong>示例</strong>:</p>
<div id="283" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsHandle handle;
units_create(&amp;handle);
units_register_defined_unit(handle, <span class="string">&quot;knots&quot;</span>, <span class="string">&quot;nautical_mile/hour&quot;</span>);
units_destroy(handle);
</pre></div>
</div>
<h2 id="290">配置管理API</h2>
<h3 id="292">units_load_config_file</h3>
<p id="293">加载配置文件</p>
<div id="295" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_load_config_file(UnitsHandle handle,
                                      <span class="keyword">const</span> <span class="keyword">char</span> *config_file);
</pre></div>
</div>
<p id="300"><strong>参数</strong>:</p>
<ul id="301">
<li id="301"><code>handle</code>: 单位系统句柄</li>
<li id="302"><code>config_file</code>: 配置文件路径</li>
</ul>
<p id="304"><strong>返回值</strong>:</p>
<ul id="305">
<li id="305"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="306"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="307"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="308"><code>UNITS_FILE_IO_ERROR</code>: 文件IO错误</li>
<li id="309"><code>UNITS_CONFIG_PARSE_ERROR</code>: 配置解析错误</li>
</ul>
<h3 id="311">units_save_config_file</h3>
<p id="312">保存配置到文件</p>
<div id="314" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_save_config_file(UnitsHandle handle,
                                      <span class="keyword">const</span> <span class="keyword">char</span> *config_file);
</pre></div>
</div>
<p id="319"><strong>参数</strong>:</p>
<ul id="320">
<li id="320"><code>handle</code>: 单位系统句柄</li>
<li id="321"><code>config_file</code>: 配置文件路径</li>
</ul>
<p id="323"><strong>返回值</strong>:</p>
<ul id="324">
<li id="324"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="325"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="326"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="327"><code>UNITS_FILE_IO_ERROR</code>: 文件IO错误</li>
</ul>
<h3 id="329">units_load_defined_units_from_file</h3>
<p id="330">从文件加载预定义单位</p>
<div id="332" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_load_defined_units_from_file(UnitsHandle handle,
                                                  <span class="keyword">const</span> <span class="keyword">char</span> *file);
</pre></div>
</div>
<p id="337"><strong>参数</strong>:</p>
<ul id="338">
<li id="338"><code>handle</code>: 单位系统句柄</li>
<li id="339">file: 文件路径</li>
</ul>
<p id="341"><strong>返回值</strong>:</p>
<ul id="342">
<li id="342"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="343"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="344"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
<li id="345"><code>UNITS_FILE_IO_ERROR</code>: 文件IO错误</li>
<li id="346">UNITS_DEFINED_UNITS_PARSE_ERROR: 已定义单位解析错误</li>
</ul>
<h2 id="348">日志API</h2>
<h3 id="350">UnitsLogCallback</h3>
<p id="351">日志回调函数类型定义</p>
<div id="353" class="lang-c editor-colors"><div class="cplusplus"><pre>
<span class="keyword">typedef</span> <span class="keyword">void</span> (*UnitsLogCallback)(<span class="keyword">const</span> <span class="keyword">char</span> *level, <span class="keyword">const</span> <span class="keyword">char</span> *message);
</pre></div>
</div>
<p id="357"><strong>参数</strong>:</p>
<ul id="358">
<li id="358"><code>level</code>: 日志级别（如 &quot;info&quot;, &quot;error&quot; 等）</li>
<li id="359"><code>message</code>: 日志消息内容</li>
</ul>
<h3 id="361">units_set_logger</h3>
<p id="362">设置日志回调函数</p>
<div id="364" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode units_set_logger(UnitsHandle handle,
                                UnitsLogCallback logger);
</pre></div>
</div>
<p id="369"><strong>参数</strong>:</p>
<ul id="370">
<li id="370"><code>handle</code>: 单位系统句柄</li>
<li id="371">logger: 日志回调函数指针</li>
</ul>
<p id="373"><strong>返回值</strong>:</p>
<ul id="374">
<li id="374"><code>UNITS_SUCCESS</code>: 成功</li>
<li id="375"><code>UNITS_INVALID_HANDLE</code>: 无效句柄</li>
<li id="376"><code>UNITS_INVALID_PARAM</code>: 参数为空指针</li>
</ul>
<h2 id="378">辅助函数</h2>
<h3 id="380">units_error_string</h3>
<p id="381">获取错误码对应的描述字符串</p>
<div id="383" class="lang-c editor-colors"><div class="cplusplus"><pre>
<span class="keyword">const</span> <span class="keyword">char</span> *units_error_string(UnitsErrorCode code);
</pre></div>
</div>
<p id="387"><strong>参数</strong>:</p>
<ul id="388">
<li id="388"><code>code</code>: 错误码</li>
</ul>
<p id="390"><strong>返回值</strong>:</p>
<ul id="391">
<li id="391">对应的错误信息字符串</li>
</ul>
<p id="393"><strong>示例</strong>:</p>
<div id="395" class="lang-c editor-colors"><div class="cplusplus"><pre>
UnitsErrorCode err = UNITS_INVALID_HANDLE;
<span class="keyword">const</span> <span class="keyword">char</span>* msg = units_error_string(err);
<span class="comment">// msg = &quot;Invalid handle&quot;</span>
</pre></div>
</div>
<h2 id="401">常用单位示例</h2>
<p id="402">以下是一些常用单位的表示方法：</p>
<ul id="403">
<li id="403">长度: meter, kilometer, foot, inch, mile</li>
<li id="404">质量: kilogram, gram, pound, ounce</li>
<li id="405">时间: second, minute, hour, day</li>
<li id="406">温度: celsius, fahrenheit, kelvin</li>
<li id="407">电流: ampere</li>
<li id="408">物质的量: mole</li>
<li id="409">发光强度: candela</li>
<li id="410">角度: degree, radian</li>
<li id="411">速度: meter/second, kilometer/hour, mile/hour</li>
<li id="412">压力: pascal, bar, psi</li>
</ul>
<h2 id="414">注意事项</h2>
<ol id="415">
<li id="415">所有 API 调用都需要有效的 <code>UnitsHandle</code></li>
<li id="416">字符串参数不能为 <code>NULL</code>，需要进行有效性检查</li>
<li id="417">缓冲区操作需要注意缓冲区大小，防止溢出</li>
<li id="418">使用完毕后必须调用 <code>units_destroy</code> 释放资源</li>
<li id="419">错误处理应该检查返回值并采取适当措施</li>
<li id="420">线程安全且可重入</li>
</ol>

                </body>
            </html>
            